OpenEuphoria

Documentation writing guideline:

Routines should be written so the "dot notation pre-processor" can make sense of the routine.

<eucode>
sequence str = "hello"

-- ** Bad **
puts(1, str )

-- ** Good **
puts( str, 1 )

--> ** since **
puts(str) --> makes sense
str.puts() --> makes sense
str.puts(1) --> makes sense

</eucode>



Some features are suggested so that the intermediate text file is easy to parse. Then any desired look can be created by running a simple parsing utility.

* the description is one line that should read as if the identifier is the first word in the sentence. ** user routines do not need a "Description:" header
** <built-in> routines do require a "Description:" header
* the description is one line that should read as if the identifier is the first word in the sentence. (does not need a Description: header)
* parameter names in a routine should be descriptive
* Parameters: header only needs to be followed by numbered description of parameters (since other information can be parsed out of the signature)
* Returns: must allow various return formats like ##integer##, ##sequence##
* New technical words are in **bold** followed "by a quoted definition."
* Examples should be self contained. It should be possible to copy and paste the example into the WEE editor and have the example execute. (Therefore must have all include files, all variables declared, ...)
* expected output in an example can be a comment line such as ##--> 0 for failure##
* See Also: header, the items can be separated by just a blank space

A sample documented routine could look like:

* See Also: header, the items can be separated by just a blank space

{{{
--**
-- checks whether two objects can perform a sequence operation together.
-- Parameters:
-- # one of the objects to test for compatible shape
-- # the other object
-- Returns:
-- integer
-- * 1 ; possible operation between ##a## and ##b##
-- * 0 ; fails
-- Comments:
-- The **shape** of an object "considers length, branches, and length of branches."
-- Shapes are **compatible** if "it is possible to perform an operation on every element."
-- Note:
-- An ##atom## is always compatible with a ##sequence## of any shape.
-- Example 1:
-- <eucode>
--
-- include std/sequence.e
-- integer i
--
-- i = binop_ok({1,2,3},{4,5})
-- ? i
-- --> 0
--
-- i = binop_ok({1,2,3},4)
-- ? i
-- --> 1
--
-- i = binop_ok({1,2,3},{4,{5,6},7})
-- ? i
-- --> 1
-- </eucode>
-- See Also:
-- [[:series]]

public function binop_ok(object a, object b)
if atom(a) or atom(b) then
return 1
end if

if length(a) != length(b) then
return 0
end if

for i = 1 to length(a) do
if not binop_ok(a[i], b[i]) then
return 0
end if
end for

return 1
end function
}}}

The "look" of the resulting documentation can vary. It all depends on an intermediate parsing program.

== EXAMPLE ONE
=== First Signature Style

which may produce documentation that looks like

@[:binop_ok|]
==== binop_ok
checks whether two objects can perform a sequence operation together.
<eucode>
include function2.e
public
function binop_ok(
object a,
object b
)
</eucode>

| //type// | //parameter// | //argument// | //default// |
| x,,1,, | a | one of the objects to test for compatible shape | |
| x,,2,, | b | the other object | |


===== Returns:
|##integer## | |
| ##1## | possible operation between ##a## and ##b## |
| ##0## | fails |

===== Comments:
The **shape** of an object "considers length, branches, and length of branches."
Shapes are **compatible** if "it is possible to perform an operation on every element."
===== Note:
An ##atom## is always compatible with a ##sequence## of any shape.
===== Example 1:
<eucode>

include std/sequence.e
integer i

i = binop_ok({1,2,3},{4,5})
? i
--> 0

i = binop_ok({1,2,3},4)
? i
--> 1

i = binop_ok({1,2,3},{4,{5,6},7})
? i
--> 1
</eucode>
===== See Also:
~| series ~|

== EXAMPLE TWO
=== Alternative Signature Style

==== binop_ok
checks whether two objects can perform a sequence operation together.
<eucode>function binop_ok(object a,object b)</eucode>
| | //type// | //parameter// | //argument// | //default//
| **binop_ok**
| | **(**
| | x,,1,, | a | one of the objects to test for compatible shape
| | x,,2,, | b | the other object
| | **)**
| //routine//: | ##function##
| //include file//: | ##function2.e##
| //namespace//: | ##mystd##
| //scope//: | ##public##

===== Returns:
|##integer## | |
| ##1## | possible operation between ##a## and ##b## |
| ##0## | fails |


== EXAMPLE THREE
=== Alternative Signature Style

==== binop_ok
checks whether two objects can perform a sequence operation together.
<eucode>
function
binop_ok (
object a, -- first object for comparison
object b -- second object for comparison
)
</eucode>

===== Returns:
|##integer## | |
| ##1## | possible operation between ##a## and ##b## |
| ##0## | fails |
~| series ~|